home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / ab20_archive / languages / assembly / powervisor_113.lzh / docs / TechnicalInfo < prev    next >
Text File  |  1992-01-27  |  12KB  |  276 lines
  1. *----------------------------*
  2. * Reference : Technical Info * Mon Jan 27 20:25:01 1992
  3. *----------------------------*
  4.  
  5. ============================== Introduction ==================================
  6.  
  7. This file contains some technical info and details about PowerVisor that
  8. can be important to people writing scripts. If you are unsure about some
  9. special feature you may find it here.
  10.  
  11.  
  12. ========================== Commandline parsing ===============================
  13.  
  14. This section contains very detailed information about commandline parsing.
  15.  
  16. The following steps happen when a command string is parsed. This parsing
  17. happens whenever a command is entered or for commands that are executed
  18. as arguments for other commands (like 'for', 'to', 'with', ...).
  19.  
  20.    -  Skip spaces
  21.    -  Check for the ²comment character (';' by default)
  22.       If it is a comment, the rest of the commandline is ignored and
  23.       the parsing is stopped (0 is returned)
  24.    -  Checks if there is an ²output suppressor ('-' by default)
  25.       If there is one, the output to the ³current logical window is disabled.
  26.    -  Skip spaces
  27.    -  See if the command is an ¹alias and if it is, replace the command string
  28.       with the ²alias string. All '[]' symbols in the alias string are
  29.       replaced with the rest of the commandline after the original command
  30.    -  Skip spaces
  31.    -  Check for the comment character (';' by default)
  32.       If it is a comment, the rest of the commandline is ignored and the
  33.       parsing is stopped (0 is returned)
  34.    -  Checks if there is an output suppressor ('-' by default)
  35.       If there is one, the output to the current logical window is disabled
  36.    -  Skip spaces
  37.    -  See if there is a '{' (²command group). If there is we start parsing
  38.       each individual command in this group (seperated by ';') with the
  39.       algorithm described here. Note that comments do not work in groups
  40.       except when the comment appears in the alias string. After parsing
  41.       each individual command in the group, we stop the current parsing
  42.       (we return the result code of the last command in the group)
  43.    -  If there is no '{' we check if the command is an assignment.
  44.       If it is we perform the assignment and stop the parsing (we return
  45.       the assigned value)
  46.    -  If we are still here, we have a normal command
  47.    -  Skip spaces
  48.    -  See if the command exists. If it does not exist we generate a
  49.       'Syntax Error'
  50.    -  If the command is empty we simply continue the last memory listing
  51.       (or disassembly)
  52.    -  If the first argument of the command is a '?' we get the commandline
  53.       ¹template and show it (0 is returned if successful)
  54.    -  Finally we come to execute the command (the result of this command
  55.       is returned)
  56.  
  57. The situation is a bit different for the command typed in on the commandline
  58. (the stringgadget). BEFORE the above algorithm is executed, the following
  59. additional steps are called :
  60.  
  61.    -  Set the starting page for the current logical window to 0. This means
  62.       that we will get '-MORE-' when a full page of output has passed
  63.    -  Skip spaces
  64.    -  Check if there is a ³feedback suppress character in front of the line
  65.       ('~' by default). If there is, we remove it from the commandline
  66.       and skip the following step
  67.    -  Feedback the command on the current logical window (show the command
  68.       as it was typed in)
  69.    -  Display the ²'-BUSY-' prompt
  70.    -  Skip spaces
  71.    -  Check if there is a ²quick-execute char ('\' by default) in front of
  72.       the commandline. When there is one we skip the following step and
  73.       skip the last step of this procedure
  74.    -  Check if there is a ²'Pre' command to execute. A 'Pre' command is
  75.       a command that is executed everytime the user enters a command (See
  76.       'TheWizardCorner' for more information). If there is a 'Pre' command
  77.       it is executed (with the previous procedure for parsing)
  78.    -  If the previous 'Pre' command failed (if it was executed) we
  79.       stop further parsing
  80.    -  Use the previous procedure for parsing to parse the rest of the
  81.       commandline
  82.    -  (This step is also skipped if the quick-execute char is present)
  83.       Check if there is a ²'Post' command to execute. A 'Post' command is
  84.       a command that is executed AFTER execution of the commandline
  85.       (See 'TheWizardCorner' for more information). If there is a 'Post'
  86.       command it is executed (with the previous procedure for parsing
  87.  
  88. From these two procedures you can draw some conclusions :
  89.  
  90.    -  Alias expansion is only done once. This means that you can't use
  91.       an alias in an alias. However, when you use this second alias
  92.       in a ²group operator, it will be converted. For example :
  93.  
  94.          alias disp 'print []'
  95.          alias print 'disp []'
  96.  
  97.       will simply redefine 'print' to mean 'disp' and 'disp' to mean 'print'.
  98.  
  99.          alias disp '{print []}'
  100.          alias print '{disp []}'
  101.  
  102.       will cause an infinite loop when you call any of these two commands.
  103.       This is because alias expansion is done again for each command in
  104.       a group. PowerVisor checks for stackoverflow so don't worry.
  105.  
  106.    -  If you want more ²prefix operators on the same commandline you have
  107.       to observe the following order :
  108.  
  109.          ~ \ -
  110.  
  111.  
  112. ================================ Hold mode ===================================
  113.  
  114. While in ²hold mode, PowerVisor only waits for the ²hot key signal and for
  115. a crash. All other signals are ignored until the window is back again.
  116.  
  117.  
  118. =========================== Expression parsing ===============================
  119.  
  120. Default ²operator priorities (you can change them with the 'pvcall' command).
  121. Note that these priorities are the same as used in standard C.
  122.  
  123.    Priorities between 1 and 10 are supported (1 is low priority)
  124.  
  125.    Op      Function            Default priority
  126.    --------------------------------------------
  127.    *       Multiply            10
  128.    /       Divide              10
  129.    %       Modulo              10
  130.    +       Add                 9
  131.    -       Subtract            9
  132.    <<      Left shift          8
  133.    >>      Right shift         8
  134.    >       Greater than        7
  135.    <       Less than           7
  136.    >=      Greater or equal    7
  137.    <=      Less or equal       7
  138.    !=      Not equal           6
  139.    ==      Equal               6
  140.    &       And                 5
  141.    ^       Xor                 4
  142.    |       Or                  3
  143.    &&      Logical and         2
  144.    ||      Logical or          1
  145.  
  146.  
  147. Here are some remarks for expression evaluation :
  148.  
  149.    -  ²Decimal integers always start with a non-zero digit
  150.    -  Hexadecimal integers start with a zero digit or with '$'
  151.    -  ²String pointers always start with double quotes '"'
  152.    -  '-','~' and '!' are unary operators. The element directly after
  153.       the operator is evaluated and the operator is applied.
  154.       This means that these unary operators have the highest priority
  155.       possible. Unary operators are ALWAYS evaluated first.
  156.    -  The ²'*' operator is also a unary operator. The same comments
  157.       as for the normal unary operators apply here. The only difference
  158.       is the dot '.' that may appear after the evaluated element.
  159.    -  The ²':' operator expects two string arguments (these string arguments
  160.       do not support the '\' operator). The first argument (before
  161.       the ':') is the list name. If you omit this argument the current list
  162.       is used. The second argument (after the ':') is the list element.
  163.       If you omit this argument the first element in the list with a name
  164.       is used.
  165.    -  The ²'&' operator. After the '&' operator follows a ':' operator.
  166.    -  The ²'@' operator. The following '@' elements are supported :
  167.          d0 ... d7
  168.          a0 ... a6
  169.          sp
  170.          pc
  171.    -  A ²group operator '{' is evaluated by executing all commands in
  172.       the group. The result of the group is the result of the last
  173.       command in the group.
  174.       The group operator is disabled when you use the expression evaluator
  175.       from within a debug task.
  176.    -  A normal string starting with a single quote '''.
  177.       The following steps are used to evaluate a string starting with
  178.       a quote :
  179.          -  The first thing to do is to check if the string is a symbol in
  180.             the current debug task. This check is ²case sensitive.
  181.             No ¹abbreviations are possible.
  182.          -  If the previous check failed we check if the string is an
  183.             abbreviation for an element in the current list.
  184.             This check is ²case insensitive.
  185.          -  Otherwise an error is generated
  186.    -  A name. This is a sequence of characters starting with a alphanumeric
  187.       character or an underscore '_'.
  188.       The following steps are used to evaluate the name :
  189.          -  First we check if the name is a variable or a function.
  190.             This check is case insensitive. No abbreviations are possible.
  191.          -  If the previous check failed we check if the name is a
  192.             loaded ²library function (with 'loadfd'). This check is case
  193.             insensitive. No abbreviations are possible.
  194.          -  Otherwise we continue with the evaluation for strings with
  195.             a single quote.
  196.  
  197.  
  198. Here follows the ¹syntax for ²PowerVisor expressions :
  199.  
  200.    <name> is a syntaxical element
  201.    [] indicate optional items
  202.    {} repeat the items 1 or more times
  203.    |  choose between several items
  204.    () group items
  205.    #  is used for the ascii value of a character
  206.    \  all items after this operator are excluded from the list
  207.       before this operator (the 'all-except' operator)
  208.    .. indicate a range
  209.  
  210.  
  211.    <expression> ::= <element> [<operator> <expression>]
  212.    <element> ::= <integer> | <unary operator> | <brackets> |
  213.             <list operator> | <list address operator> | <group>
  214.  
  215.    <integer> ::= <hexadecimal int> | <decimal int> | <variable> |
  216.             <function> | <string pointer> | <debug symbol> |
  217.             <current list element> | <register> | <library function>
  218.  
  219.    <hexadecimal int> ::= ('0' | '$') [{<hex-digit>}]
  220.    <decimal int> ::= ('1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9') [{<dec-digit>}]
  221.  
  222.    <variable> ::= <name>
  223.  
  224.    <function> ::= <name> '(' [ <expression>
  225.             [{<whitespace> <expression> }]] ')'
  226.  
  227.    <debug symbol> ::= <name> | <string>
  228.  
  229.    <current list element> ::= <name> | <string>
  230.  
  231.    <library function> ::= <name> '(' [ <expression>
  232.             [{<whitespace> <expression> }]] ')'
  233.  
  234.    <register> ::= '@' ( ('d'|'D')(<dec-digit> \ ('8'|'9')) |
  235.             ('a'|'A')(<dec-digit> \ ('8'|'9')) | 'sp' | 'pc' | 'sr')
  236.  
  237.    <unary operator> ::= <negation> | <logical not> | <bitwise not> |
  238.             <address operator>
  239.    <negation> ::= '-' <element>
  240.    <logical not> ::= '!' <element>
  241.    <bitwise not> ::= '~' <element>
  242.    <address operator> ::= '*' <element> ['.' ('b'|'w'|'l')]
  243.  
  244.    <list operator> ::= [<name>] ':' [<name> | <string>]
  245.    <list address operator> ::= '&' <list operator>
  246.  
  247.    <group> ::= '{' [{<command>}] ['}']
  248.    <command> ::= [<prefix operator>] ((<name> [{<expression>|<string>|
  249.             <name>}]) | <assignment>)
  250.    <prefix operator> ::= '-' | ';'
  251.    <assignment> ::= (<name> | <register> | <address operator>) '='
  252.             <expression>
  253.  
  254.    <brackets> ::= '(' <expression> [')']
  255.  
  256.    <name> ::= ('_'|<alphachar>) [{'_'|<alphachar>|<dec-digit>}]
  257.    <string> ::= ''' [{<string-char>|<quote operator>|<strong quote>}] [''']
  258.    <string pointer> ::= '"' [{<stringptr-char>|<quote operator>|
  259.                         <strong quote>}] ['"']
  260.    <quote operator> ::= '\' (<integer quote>|<char quote>)
  261.    <strong quote> ::= '·' <endchar> {#<x>} <endchar>
  262.    <char quote> ::= <hex-digit> <hex-digit>
  263.    <integer quote> ::= '(' <expression> [<whitespace> <formatstring>] ')'
  264.    <formatstring> ::= {#<x> \ ')'}
  265.  
  266.    <alphachar> ::= 'a'|'A'|'b'|'B'|...|'z'|'Z'
  267.    <hex-digit> ::= <dec-digit>|'a'|'b'|'c'|'d'|'e'|'f'|'A'|'B'|'C'|'D'|
  268.             'E'|'F'
  269.    <dec-digit> ::= '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
  270.    <whitespace> ::= ' '|','|#9
  271.    <stringptr-char> ::= #<x> \ ('\'|'"')
  272.    <string-char> ::= #<x> \ ('\'|''')
  273.    <x> ::= 1..255
  274.  
  275.  
  276.